feat(local-model): pick the coding agent per session, with Pi and DeepSeek Harness, and install a missing one - #806

Stacked on #804 (the model library). The base of this PR is that branch, so the diff shows only what is new here. Merge #804 first; GitHub then retargets this one to master.

What this changes

"Run a local model" is the window that installs a coding model on the Mac the Codeman server runs on. A model is driven by a coding agent CLI (a "harness"). Until now an installed model knew exactly one agent, the one it was installed with, and only OpenCode and Claude Code were offered.

This PR makes the agent a per-session choice and adds two agents:

• Pick the agent when you start a session. The installed screen has a new block, "Start a session with": one chip per agent the model can be run with. The device remembers the agent a session was last started with.
• Pi and DeepSeek Harness are offered, next to OpenCode and Claude Code.
• Install a missing agent from the same screen. A chip that says "Not installed" shows the literal install command, and the main button becomes "Install Pi" (or whichever agent). The model stays ready while the installer runs.
• Pi learns the model's context window (a fix to the custom model feature as a whole, in its own commit).

The four agents, and what each rests on

How to read the last column. The runs were made on 2026-11-10 on Linux, through Codeman's own custom model launch:

• "a real model" is Ollama 0.13.0 with a 1.7B model on a CPU;
• "a scripted endpoint" replays that runtime's stream of a tool call. It proves the agent's side of the protocol, not what a model does with the prompt.

None of it ran on a Mac or on the pinned runtime (Ollama 0.40.15). Every agent sent the name:tag model name unchanged.

Decisions a maintainer should look at

1. DeepSeek Harness is offered on thin evidence. Its row is not gated although no turn finished against a real model on this feature's runtime (the test box ran out of memory first). What speaks for it: the scripted round trip, and that its custom endpoint recipe was already verified with a real model on a llama.cpp server (docs/custom-model-endpoints.md). It is ranked last and never installed from here, so only a Mac that already has it set up sees it as startable. To gate it again: gated: true on its row in src/config/local-model-catalog.ts, one line.
   Two things today's DeepSeek Harness (0.2.2-rc.1 with dsh-TUI 0.19.0) does that are worth knowing, both independent of this PR:
   • A setup guide opens in every session until a person has finished it once. In a tab that is a few key presses. For a script it is a trap, because the guide's cursor is the same glyph as the composer; the skill PR on top of this one (feat(skill): spawn a local model worker with the coding agent of your choice (local:pi, local:deepseek) #807) refuses such a worker instead of typing into it.
   • Its transcript file was renamed (session.v4.jsonl.zstd), so Codeman's response viewer and last-response are empty for a dsh session on that version. That is a bug of its own, for every dsh session, and is not fixed here.
2. DeepSeek Harness is never installed from this window. dsh is a launcher: its install command installs the launcher, and a session also needs a terminal profile, which is third-party code behind its own consent in the Run menu. So it shows "Needs setup" until the Run menu can start it. The rule reads the registry entry's discovery.launcherProfile, not the CLI id. Folding the profile install into this window is possible and is a decision of its own.
3. Pi has two rough edges that are not fixed here, both because a custom model session gives Pi a home directory of its own:
   • it downloads its two search tools again at every start (needs the network; PI_OFFLINE=1 skips it);
   • it asks "Trust project folder?" in every such session when a folder above the working directory holds agent skills, because the answer is stored in the home it does not keep.
     A person in a tab can answer the question. A script cannot, which is why the follow-up for the codeman skill starts Pi with --no-approve.
4. "Start a session" now needs an agent that can be started. With none on the Mac the button is "Install OpenCode" instead of a session start that fails in the launcher.

How it is built

• The launch check never asked about the agent, only about the endpoint and the model, so nothing in the safety rules changes. One model is still loaded and connected at a time.
• GET /api/local-model gains install.harnesses[]: { cli, cliLabel, default, status, installCommand?, slowFirstTurn?, readyMark?, error?, actions }. status is ready, installable, installing or setup-needed. readyMark is a literal the agent's composer draws once it takes input, for a script that waits before its first prompt; only a measured mark is listed (OpenCode ┃, DeepSeek Harness ❯, and Claude Code's shift+tab from its registry entry; Pi has none on purpose, its composer is painted before it accepts Enter).
• install.cli stays the default agent for a client that reads only that field (the codeman skill shipped in 1.50.0 does). It now names an agent that can be started whenever one can, never one that was uninstalled.
• POST /api/local-model/agent { cli } installs one more agent beside an installed model. It is deliberately not a job of the install state machine: a job would put a working model into failed on an npm error and refuse every session until someone cleared it. The state stays installed, the installer runs in the background through the same install slot and the same compiled stock command as the install's own agent step, one at a time, audited (cli_install, via: "local-model"), and its outcome is kept in memory only. The request carries a CLI id, never a command.
• A switch to another model no longer refuses because the agent that model was checked with is gone, when another agent that can run it is on the Mac.
• The catalogue: pi is no longer gated, deepseek is a new row, a row may carry readyMark, and every row asks for 65,536 tokens (nothing below was run, and no model row offers less, so no Mac's recommended model changes). The catalogue header has a table of what each row rests on.

The Pi fix (commit a5a1b6f9, independent of the rest)

A Pi session on any custom endpoint got a model list entry with only the model id. Pi then takes the model for a 128,000-token one and asks for 16,384 reply tokens, so on a 65,536 window it never compacts before the server's real window is full. The entry now carries contextWindow and maxTokens when the endpoint's context length is known, the same two figures the DeepSeek Harness recipe already had. Measured on pi 1.5.2: pi --list-models shows the window and the request carries max_tokens: 8192.

API (experimental routes, outside the stable /api/v1 contract)

Admin only in multi-user mode, checked before the body is parsed, like every other route of the feature.

Testing

• CI on this PR is the full gate.
• 41 targeted test files, 1,931 tests on the final tree: every test/local-model-* and test/routes/local-model-* file, the custom model tests, the i18n harvest, both CLI id-branching guards and the HTTP contract test.
• New tests: the agent rows as a pure function (order, default, every status), the agent install in the service (started, failed, retried, one at a time, already there, refused, ended by a server stop, the state file untouched), the route (admin gate, schema, 400 and 409 with their sentences), the launcher rule and the readiness mark in the harness facts, the Pi model entry, and 15 window tests (select, start with the selected agent, install, failure, keyboard, a stopped model, Chinese, text shown as text, and a chip that was only looked at never hides "Start a session" when the window is opened again).
• Typecheck, lint, format check, frontend syntax and public assets checks: clean.
• npm run test:browser -- test/local-model-ui.browser.test.ts (real Chromium, not part of the gate): 11 passed, one of them new (the chips wrap inside the window at 1440, 390 and 320 px, the install command included, with one tab stop). The screen was also looked at on a dark and a light skin with a scratch script.
• The combined tree of this branch and feat(local-model): list every model that fits, and add Muse Glimmer 30B and Ornith 1.0 9B #803 (more models) was built and its catalogue, recommendation and route tests pass (565 tests), so the two merge without a semantic conflict.

Run on a real Mac (2026-11-12)

A MacBook Pro (M5 Pro, 48 GB, macOS 27.2) with the pinned runtime, Ollama 0.40.15. Its Codeman ran the tree of this stack (#803 to #808) merged onto 1.50.1. The window was driven by real clicks, from a Chromium on another machine through an SSH forward to the Mac's own server, so every state on screen was the Mac's.

• The chips on a real install: OpenCode and Claude Code startable, Pi "Not installed" with its command under it, DeepSeek "Needs setup".
• "Install Pi", by a real click: npm install -g --ignore-scripts @earendil-works/pi-coding-agent ran for about 5 seconds. The chip went from "Installing" to startable, the install state stayed installed the whole time, and the audit log holds the cli_install entry with via: "local-model".
• A Pi session started from the window, on Qwen3.6 35B-A3B: Pi 1.5.2 showed a 131k window in its footer (the context window fix of this PR, seen working), wrote a module and its test, and ran it: 6 tests pass, about 40 seconds for the turn.
• OpenCode sessions on three models (Qwen3.5 9B, Ornith 1.0 9B, Qwen3.6 35B-A3B) each finished a turn with a tool call.
• Pi's rough edges on the Mac: it downloaded fd and ripgrep at the start of every session there too. It did not ask about folder trust, because no folder above the project holds agent skills on that Mac.
• The runtime ignores max_completion_tokens: asked for 64 tokens, Ollama 0.40.15 returned 1,235. With max_tokens: 64 it returned 64. DeepSeek Harness caps its requests with the former, so its small side requests run uncapped on this runtime. One more reason its row is ranked last.

Not run on the Mac: DeepSeek Harness (it is not set up there), and Claude Code ON the local model (Claude Code ran there as the cloud lead of the skill test in #807).

Not proven, stated plainly

• One Mac only (M5 Pro, 48 GB).
• Claude Code was not run on the local model in this round (its row shipped in 1.50.0).
• DeepSeek Harness has no finished turn against a real model on either version; both of its tool round trips are scripted.
• Only Pi's install ran for real. OpenCode's and Claude Code's go through the same code with their own stock commands, and were exercised through fakes.
• The window was driven in Chromium, against the Mac's server. It was not looked at inside the macOS app's WKWebView.

Files

Server: src/local-model/{install-job,harness-facts}.ts, src/types/{local-model,local-model-install}.ts, src/web/routes/local-model-routes.ts, src/web/schemas.ts, src/config/local-model-catalog.ts, src/custom-model-injection.ts. Window: src/web/public/{local-model-ui.js,styles.css,i18n.js}. Tests: test/local-model-{install-job,install-service,harness-facts,catalog,recommend,ui}.test.ts, test/routes/local-model-routes.test.ts, test/custom-model-injection.test.ts. Docs: CLAUDE.md, src/web/CLAUDE.md, docs/{local-models,api-reference,architecture-invariants,custom-model-endpoints}.md.